Skip to main content

ValkyrAI Troubleshooting Guide

This comprehensive troubleshooting guide addresses common issues you might encounter when working with ValkyrAI and provides solutions to help you resolve them quickly.

Table of Contents​

OpenAPI Specification Issues​

Symptoms​

You may encounter errors during OpenAPI specification validation, such as:

org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 26, Warning count: 7
Errors:
        -attribute components.schemas.EventLog.properties is not of type `object`
        -attribute components.schemas.ContentData.properties is not of type `object`
        -attribute components.schemas.Login.properties is not of type `object

Solution​

  1. Review your spec files (api.yaml and api.hbs.yaml) to remove any duplicate or auto-generated fields (such as id, created_date, modified_date, etc.).
  2. Use $ref pointers for all object definitions instead of inline objects.
  3. Validate your schema with an OpenAPI linter before code generation to ensure compliance.

Important: It is highly recommended not to disable spec validation. Skipping validation may lead to bugs, compilation errors, or runtime failures.

SecureField and Encryption Issues​

Symptoms​

You may encounter encryption and decryption issues with SecureField, such as:

decryption failure: Tag mismatch
SQL Error: Cannot convert string '\x05\x86k\x93\x0A\xD8...' from binary to utf8mb4

Solution​

  1. Ensure that a valid THORAPI_SECRET_KEY is generated using the provided generatekey command:

    java -jar lib/generator-<valkyrai_version>-exec.jar generatekey

  2. Set the generated key as an environment variable:

    export THORAPI_SECRET_KEY=generatedPrivateKey

  3. Adjust database column sizes to account for the enlarged ciphertext. Encrypted values are typically much larger (often 2x or more) than their plaintext equivalents.

  4. Test encryption and decryption utilities to verify that encrypted data can be reliably decrypted.

Warning: Losing the THORAPI_SECRET_KEY will result in irreversible data loss. Invest in a robust key management system for long-term data security.

Column Size for Encrypted Data​

One factor in the use of SecureField feature is that an encrypted value is much larger (often 2x or more) the size of the same plaintext value. ThorAPI generates column sizes to accommodate these encrypted values as well as validations on these columns that accommodate the size of the plaintext.

This results in validations on field size that are sized differently to accommodate the larger size of encrypted data.

AspectJ Weaving and Runtime Initialization Failures​

Symptoms​

You may encounter AspectJ weaving issues, such as:

org.aspectj.lang.NoAspectBoundException: Exception while initializing SecureFieldAspect: java.lang.NoSuchMethodException: ...aspectOf()

or

Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [com.valkyrlabs.valkyrai.controller.AuditingAspect]: Factory method 'auditingAspect' threw exception with message: Exception while initializing com.valkyrlabs.valkyrai.controller.AuditingAspect: java.lang.NoSuchMethodException: com.valkyrlabs.valkyrai.controller.AuditingAspect.aspectOf()

Solution​

  1. Always compile and build the project using Maven (or the designated build tool) which correctly integrates AspectJ weaving.

  2. Avoid compiling with IDEs that use javac by default (which may bypass AspectJ integration).

  3. Ensure your build configuration (pom.xml) explicitly includes AspectJ dependencies and plugins.

  4. Close all IDE windows, terminals, and kill any process that might be holding open a file in the project path.

  5. Run a clean build:

    mvn clean install

Note: Avoiding or bypassing the Maven build process can result in subtle data errors such as storing cleartext values instead of encrypted data.

File Contention and Build Process Issues​

Symptoms​

You may encounter file contention issues during the build process, such as:

shell-init: error retrieving current directory: getcwd: cannot access parent directories
Error assembling JAR: ... file is locked
pwd: error retrieving current directory: getcwd: cannot access parent directories

Solution​

  1. Close all IDE windows, terminals, and any processes that might be locking files in the project directory.

  2. Perform a clean build:

    mvn clean install -DskipTests

  3. If you run ./vai and choose "clean" option, your generated spring directory will be moved to the trash. If you attempt to execute the service from that folder, it will likely fail. You need to change directory back to the new generated spring folder.

Code Generation and File Overwrite Issues​

Symptoms​

You may notice that CodeGen skips overwriting existing files:

[INFO] writing file ~/workspace/ValkyrAI/generated/spring/src/main/java/com/valkyrlabs/api/WorkflowApiDelegate.java
[INFO] Implementation file ~/workspace/ValkyrAI/generated/spring/src/main/java/com/valkyrlabs/api/WorkflowStateApiController.java is not overwritten

Solution​

  1. Utilize the provided ./vai script to clean previous code generation outputs before re-running the generator.
  2. Confirm or automate the overwrite options using prompts or flags in the generation script to ensure that the latest code is output correctly.

Note: Manual modifications of generated code should be avoided; if persistent changes are needed, update the CodeGen templates found under /src/main/resources/templates.

Naming Conventions and Reserved Word Conflicts​

Symptoms​

You may encounter naming issues when using reserved words (SQL, Java, or ThorAPI-specific) or improper capitalization in your OpenAPI specification:

Error executing DDL: 'alter table exec_module add column schema varchar(3000)'
cannot find symbol variable oASSimpleSchema

Solution​

  1. Avoid using reserved words. For example, rename 'Content' to 'ContentData' and 'Mono' to 'MonoResource'.
  2. Follow best practices for naming—use clear and consistent capitalization (camelCase for Java, snake_case for SQL).
  3. Consider safe alterations where reserved words must be used.

Reserved Words (Partial List):

  • URL Characters: %, ?, *, @, !, (, )
  • Java Keywords: String, Float, Integer, Object, Long, Array, Boolean
  • SQL Keywords: UNION, JOIN, SELECT, INSERT, UPDATE, DELETE, SCHEMA, IN
  • ThorAPI Objects: ApiUtil, MediaType, Mono, Content

Workarounds:

If you must use a reserved word, modify it to avoid conflicts. For example:

  • "Content" ➔ "ContentData"
  • "Mono" ➔ "MonoResource"
  • "schema" ➔ "oasSchema"
  • "in" ➔ "oasIn" or "location"

Database Schema Mismatches and Data Truncation​

Symptoms​

You may encounter database schema mismatch issues, such as:

Data truncation: Data too long for column 'country'
Column length too big for column 'bio_url' (max = 16383); use BLOB or TEXT instead

Solution​

  1. Align schema updates with proper migration tools (such as Liquibase) to manage the changes safely.

  2. If updating a maxLength property, verify existing data sizes or truncate the data as needed to fit the new constraints.

  3. For very large text fields, choose a significantly higher size to force the properly sized column:

    bioUrl:
      type: string
      description: More in-depth information about you and your account
      maxLength: 100000

Note: Thorough testing on staging environments before production deployment can prevent runtime failures.

Inheritance and allOf Issues in OpenAPI Specifications​

Symptoms​

You may encounter issues with using 'allOf' for inheritance in OpenAPI definitions:

Type '(result: void, error: FetchBaseQueryError, { id }: Pick<Solution, "id"> & Partial<Solution>) => { type: "Solution"; id: unknown; }[]'

Solution​

  1. For leaf objects, simplify the OpenAPI definition by removing the allOf combination and explicitly defining only the required properties.
  2. Alternatively, refactor the inheritance structure to avoid duplicate property definitions, ensuring that the client and server code remain in sync.

Example:

# Before
Solution:
  allOf:
    - $ref: '#/components/schemas/BaseEntity'
    - type: object
      properties:
        buildOutputId:
          type: string
          format: uuid

# After
Solution:
  type: object
  properties:
    buildOutputId:
      type: string
      format: uuid

Missing Generated Files or Obsolete References​

Symptoms​

You may encounter issues where generated code references schema components that no longer exist or are mistyped:

Error: ... components/schemas/BuildUpdate is missing
SpecValidationException indicating missing definitions for endpoints

Solution​

  1. Ensure that all schema references in the OpenAPI specs are current and correct.
  2. Remove any obsolete or redundant references.
  3. Use consistent naming and capitalization across all schema definitions.
  4. Run the CodeGen process after a complete cleanup.

Object Properties and additionalProperties Issues​

Symptoms​

You may encounter issues when using object properties or additionalProperties in your OpenAPI specifications:

Error: Association '... securitySchemes' targets the type 'java.lang.Object' which is not an '@Entity' type
Errors related to unsupported object representations in schemas

Solution​

  1. Always define objects using a named schema ($ref) instead of inline object definitions.
  2. Replace additionalProperties definitions with explicit schema references wherever possible.
  3. Update your spec to properly distinguish between free-form objects and defined schemas.

Example:

# Before
securitySchemes:
  type: array
  items:
    type: object

# After
securitySchemes:
  type: array
  items:
    $ref: '#/components/schemas/OasSecurityScheme'

OasSecurityScheme:
  type: object
  description: a security scheme to access the api
  properties:
    name:
      type: string
      description: the name of the security scheme

Deployment and Environment Configuration Errors​

Symptoms​

You may encounter deployment and environment configuration errors:

Error executing DDL: alter table ... Data truncation errors
java.sql.SQLException: Field 'config_id' doesn't have a default value
SQL State HY000 errors related to binary-to-text conversion

Solution​

  1. Double-check deployment commands and environment variables, such as database URLs, credentials, and JPA settings.
  2. Use the provided sample commands (custom and default options) in the deployment section of the documentation to guide your configuration.
  3. Validate the environment configuration on test deployments before rolling out to production.

Example deployment command:

java -jar generated/spring/target/valkyrai-api-<valkyrai_version>.jar \
  --spring.datasource.url=jdbc:mysql://your.database.com:3306/valkyrai \
  --spring.datasource.username=dbmasteruser \
  --spring.datasource.password=YOUR_DB_PASSWORD \
  --spring.jpa.hibernate.ddl-auto=update \
  --spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQLDialect \
  --server.port=8081

Spring Security ACL and DataObject Interface Issues​

Symptoms​

You may encounter issues related to object-level security implementation using Spring Security ACL:

Compilation error: ... DataObject is not abstract and does not override abstract method setId(UUID)
Error creating bean with name 'entityManagerFactory' due to missing mapping fields

Solution​

  1. Verify that all model objects correctly implement the DataObject interface.
  2. Remove any manual additions of auto-generated fields from your OpenAPI spec, allowing ThorAPI to handle them automatically.
  3. Ensure that ACL-related tables and entities are generated as per the standard configuration.

TypeScript Code Generation Issues​

Symptoms​

You may encounter issues with the generated TypeScript clients:

src/main/typescript/valkyr_labs_com/src/thor/redux/components/form/WorkflowStateForm.tsx:282:18
280|                      className="nice-form-control"
281|                      style=
282|                    >
   |                    ^

Solution​

  1. When modifying front-end templates, be careful with CSS properties in React components.
  2. Separate the brackets with spaces to avoid conflicts with the mustache template engine:
// Change
style={{ display: 'block', marginBottom: '1rem' }} >

// To
style={ { display: 'block', marginBottom: '1rem' } } >

Spring Framework Dependency Incompatibilities​

Symptoms​

You may encounter dependency incompatibilities, especially with Spring Framework and AspectJ versions.

Solution​

  1. The specific versions of all imported libraries, especially the Spring Framework and AspectJ, have been meticulously selected and tested by hand to ensure version compatibility.
  2. When upgrading any of the libraries in the pom.xml and package.json files, please test and confirm all of the functionality of your system thoroughly.

Additional Troubleshooting Tips​

Trying to Launch Spring Boot From a Deleted Generated Folder​

If you run ./vai and choose "clean" option, your generated spring directory will be moved to the trash. If you attempt to execute the service from that folder, it will likely fail with an error such as:

shell-init: error retrieving current directory: getcwd: cannot access parent directories

Simply change directory back to the new generated spring folder:

cd ..
cd spring

Non-Fatal Test Errors​

During maven test runs, you may encounter Spring JPA DML/DDL issues creating tables for tests using the H2 embedded database engine. These may or may not impact your testing depending upon whether your test code touches upon the tables that are not able to be created.

Inner Classes and Many to Many​

ThorAPI does not yet fully support the 'oneOf' operator because it generates inner classes which are then unavailable to the Spec enhancer. There are two workarounds:

  1. Manually add the fields to the inline object definitions.
  2. Move the inline object definition to a separate object and use a $ref.

Example:

# Before
McpToolCallResponse:
  type: object
  properties:
    _meta:
      type: object
      additionalProperties: true
    content:
      type: array
      items:
        oneOf:
          - type: object
            properties:
              type:
                type: string
                enum:
                  - text
              text:
                type: string
            required:
              - type
              - text

# After
McpToolCallResponse:
  type: object
  properties:
    _meta:
      type: object
      additionalProperties: true
    content:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/McpTextContent'
          - $ref: '#/components/schemas/McpImageContent'
          - $ref: '#/components/schemas/McpResourceContent'
    isError:
      type: boolean
  required:
    - content

Conclusion​

This troubleshooting guide covers the most common issues you might encounter when working with ValkyrAI. If you encounter an issue not covered in this guide, please refer to the ValkyrAI GitHub repository or contact support@valkyrlabs.com for assistance.

Remember that regular maintenance, thorough testing, and adherence to best practices can prevent many of these issues from occurring in the first place.